Embeddings

Embeddings are numerical representations of text that are commonly used for semantic search, vector retrieval, and Retrieval-Augmented Generation (RAG). BindAI provides an embedding abstraction that separates embedding generation from the retrieval and Knowledge layers. The current implementation includes:

EmbeddingProvider
RandomEmbeddingProvider
OpenAIEmbeddingProvider

These providers can be used by applications and Knowledge/retrieval components that require vector representations of text.

What Is an Embedding?

An embedding converts content such as text into a numerical vector. Conceptually:

"The server is offline."

        |
        v

Embedding Provider

        |
        v

[0.12, -0.48, 0.73, ...]

The resulting vector represents characteristics of the input text in a mathematical space. Texts with related meanings can produce vectors that are close according to the similarity method used by the retrieval system.

EmbeddingProvider

BindAI defines an EmbeddingProvider abstraction for embedding generation. The abstraction allows embedding consumers to work with different implementations without depending directly on one embedding service. Conceptually:

Text
  |
  v
EmbeddingProvider
  |
  +---- RandomEmbeddingProvider
  |
  +---- OpenAIEmbeddingProvider
  |
  v
Vector

This separation makes it possible to change embedding implementations without redesigning the rest of the application.

RandomEmbeddingProvider

BindAI includes RandomEmbeddingProvider as a deterministic local embedding implementation. It is useful for:

Development
Testing
Local experiments
Retrieval tests
Environments where a hosted embedding API is not required

It does not represent the semantic quality of a production embedding model. The provider is primarily useful when an application needs a local embedding implementation without making an external API request.

OpenAIEmbeddingProvider

BindAI provides OpenAIEmbeddingProvider for OpenAI embeddings. The default model is:

text-embedding-3-small

The provider supports configurable embedding dimensions. For example:

from bindai_embeddings import OpenAIEmbeddingProvider

embeddings = OpenAIEmbeddingProvider(
    model="text-embedding-3-small",
    dimensions=512,
)

The provider uses the OpenAI embeddings API to generate vectors. An OpenAI API key can be supplied explicitly or obtained through the OpenAI client configuration.

Embedding Dimensions

Embedding dimensions determine the length of the generated vector. For example, an embedding configured with:

dimensions = 512

produces a vector containing 512 numerical values. Vector storage must use a compatible dimension. For example:

Embedding Provider
        |
        v
512-dimensional vector
        |
        v
512-dimensional vector index

A mismatch between embedding dimensions and vector-storage dimensions can cause indexing or retrieval failures.

Why Embeddings Are Useful

Traditional keyword search primarily looks for matching words. For example:

Document:

The application crashed unexpectedly.

A user might ask:

Why did the program fail?

The two texts use different words while expressing related concepts. Semantic retrieval can use embeddings to identify that relationship.

Semantic Search

A typical embedding-based search architecture is:

User Question
      |
      v
Query Embedding
      |
      v
Vector Search
      |
      v
Relevant Documents
      |
      v
Language Model

Documents are normally embedded ahead of time:

Documents
    |
    v
Chunking
    |
    v
Embedding Provider
    |
    v
Vectors
    |
    v
Vector Storage

At query time, the question is embedded using the compatible embedding provider and compared against stored vectors.

Document Embeddings

Knowledge documents are commonly split into chunks before embedding.

Document
    |
    v
Chunks
    |
    v
Embedding Provider
    |
    v
Vectors

Each vector represents one piece of the document. This allows retrieval to return relevant sections instead of requiring the entire document to be supplied to the model.

Query Embeddings

At query time, the user’s question can also be converted into a vector.

User Question
      |
      v
Embedding Provider
      |
      v
Query Vector
      |
      v
Vector Search
      |
      v
Relevant Chunks

The query embedding and document embeddings should be generated using compatible models and configurations.

Vector Search

Vector search compares a query vector against stored document vectors. Conceptually:

Query Vector

      |
      v

Similarity Search

      |
      +---- Document A
      |
      +---- Document B
      |
      +---- Document C
      |
      +---- ...

      |
      v

Top Results

Common similarity approaches include:

Cosine similarity
Dot product
Euclidean distance

The appropriate method depends on the embedding and vector-storage implementation.

Embeddings and Retrieval

Embeddings are one component of a larger retrieval architecture. BindAI currently provides:

Embedding abstractions
Vector retrieval
BM25 retrieval
Hybrid retrieval
Retrieval configuration
Search options
Reranking

A semantic retrieval flow can therefore be organized as:

Query
  |
  v
Embedding
  |
  v
Vector Retrieval
  |
  v
Candidate Results
  |
  v
Reranking
  |
  v
Final Results

Embedding generation and retrieval remain separate abstractions.

Hybrid Retrieval

Embeddings can be combined with lexical retrieval. For example:

                    Query
                      |
             +--------+--------+
             |                 |
             v                 v
         BM25 Search      Vector Search
             |                 |
             +--------+--------+
                      |
                      v
               Hybrid Results
                      |
                      v
                  Reranking

This can be useful when an application needs both:

Exact terminology matching
Semantic similarity

BindAI’s retrieval layer provides BM25, vector, and hybrid retrieval components.

Embeddings and Reranking

Embedding-based retrieval often produces an initial set of candidates. A reranker can then improve the ordering.

Query
  |
  v
Vector / Hybrid Retrieval
  |
  v
Candidate Results
  |
  v
Reranker
  |
  v
Final Results

BindAI provides a reranker abstraction and lexical reranking implementation. The embedding provider and reranker solve different problems and can be combined in a Knowledge pipeline.

Embeddings and Knowledge

Embeddings are an important part of the Knowledge architecture. A simplified Knowledge ingestion flow is:

Documents
    |
    v
Loading
    |
    v
Parsing
    |
    v
Chunking
    |
    v
Embedding Provider
    |
    v
Vector Data
    |
    v
Retrieval

At runtime:

User Query
    |
    v
Query Embedding
    |
    v
Vector Retrieval
    |
    v
Relevant Knowledge
    |
    v
Agent
    |
    v
Language Model

This provides the foundation for embedding-based RAG applications.

Embeddings and Memory

Embeddings and Memory should remain conceptually distinct. BindAI’s Memory subsystem supports vector-oriented memory through VectorMemoryProvider. A MemoryRecord can also contain an optional embedding. For example:

from bindai import MemoryRecord

record = MemoryRecord(
    key="example",
    value="Some information",
    embedding=[0.1, 0.2, 0.3],
)

The embedding field stores vector data on the memory record. This does not mean that every memory provider automatically generates embeddings. Embedding generation remains the responsibility of the configured embedding implementation or application.

VectorMemoryProvider

VectorMemoryProvider provides vector-oriented memory behavior. This allows Memory and embeddings to work together when an application needs similarity-based memory retrieval. The architecture can be viewed as:

MemoryRecord
     |
     v
Embedding
     |
     v
Vector Memory Provider
     |
     v
Similarity Search

This is separate from the general Knowledge document pipeline. Memory is intended for retained application or agent information, while Knowledge is intended for external/reference information.

Embeddings and Vector Storage

Embedding generation and vector storage are separate responsibilities. For example:

Embedding Provider
       |
       v
Vector
       |
       v
Vector Storage
       |
       v
Vector Retrieval

The embedding provider generates the numerical representation. The vector storage system is responsible for storing and searching those vectors. The two components must be compatible in dimensions and expected vector representation.

OpenAI Embeddings Configuration

The OpenAI embedding provider can be configured with a model and dimension. Example:

from bindai_embeddings import OpenAIEmbeddingProvider

provider = OpenAIEmbeddingProvider(
    model="text-embedding-3-small",
    dimensions=512,
)

The OpenAI API key should be provided through the application’s normal environment configuration or explicitly when constructing the provider. Do not hard-code API keys in application source code.

Embedding Provider Selection

The appropriate embedding provider depends on the application’s requirements.

Provider	Typical Use
`RandomEmbeddingProvider`	Development and testing
`OpenAIEmbeddingProvider`	Hosted semantic embeddings

When selecting an embedding provider, consider:

Retrieval quality
Supported languages
Vector dimensions
Latency
Cost
Privacy requirements
Deployment environment
Compatibility with vector storage

Embedding Model Consistency

The same compatible embedding model should normally be used for document indexing and query embedding. For example:

Document
   |
   v
text-embedding-3-small
   |
   v
Document Vector


Query
   |
   v
text-embedding-3-small
   |
   v
Query Vector

Using incompatible embedding models for the indexed documents and queries can produce poor or invalid similarity results.

Changing Embedding Models

Changing the embedding model may require reprocessing existing knowledge. For example:

Existing Documents
       |
       v
Old Embeddings
       |
       X

New Embedding Model
       |
       v
Re-embed Documents
       |
       v
New Vector Index

Applications should plan for re-indexing when changing embedding models or vector dimensions.

Embedding Quality

Embedding quality affects semantic retrieval quality. Important factors include:

Model selection
Input text quality
Chunking strategy
Language support
Vector dimensions
Similarity configuration
Retrieval strategy
Reranking

A strong embedding model cannot completely compensate for poor document preparation. The complete Knowledge pipeline should therefore be evaluated as a system.

Embeddings and Document Chunking

Chunking and embeddings are closely related. Consider:

Large Document
      |
      v
Chunk 1
Chunk 2
Chunk 3
      |
      v
Embedding Provider
      |
      v
Vector 1
Vector 2
Vector 3

If chunks are too large, retrieval may return excessive unrelated content. If chunks are too small, important context may be separated. Chunking should therefore be designed together with the embedding and retrieval strategy.

Embeddings and Metadata

Vectors should normally remain associated with useful source metadata. For example:

Vector
 |
 +-- document_id
 +-- source
 +-- category
 +-- section
 +-- version

Metadata allows retrieved vectors to be interpreted and filtered according to application requirements. The embedding itself represents the content; metadata provides additional information about that content.

Embeddings in a RAG Pipeline

A complete embedding-based RAG architecture can look like:

                    Ingestion
                       |
                       v
                   Documents
                       |
                       v
                    Chunking
                       |
                       v
                Embedding Provider
                       |
                       v
                  Vector Storage
                       |
                       |
                 Runtime Query
                       |
                       v
                 User Question
                       |
                       v
                Query Embedding
                       |
                       v
                Vector Retrieval
                       |
                       v
              Filter / Rerank
                       |
                       v
              Relevant Knowledge
                       |
                       v
                     Agent
                       |
                       v
                Language Model
                       |
                       v
                   Response

BindAI provides the embedding and retrieval abstractions needed for this architecture while allowing applications to choose the surrounding storage and application components.

Embeddings Are Not Tools

An embedding provider and a BindAI tool serve different purposes. An embedding provider transforms information:

Text -> Vector

A BindAI tool is executable Python functionality that an agent can invoke:

Model
  |
  v
Tool Call
  |
  v
Python Function
  |
  v
Tool Result

An application can use both. For example, a tool might retrieve live information from an external API while Knowledge uses embeddings to retrieve reference documentation.

Embeddings and Agents

Embeddings normally operate below the agent’s conversational interface. A simplified architecture is:

User
 |
 v
Agent
 |
 v
Knowledge
 |
 v
Retriever
 |
 v
Embedding Provider
 |
 v
Vector Search
 |
 v
Relevant Context
 |
 v
Agent / Model

The agent does not need to know the implementation details of the embedding provider. This separation allows applications to change embedding providers without redesigning the agent interface.

Embedding Errors

Embedding operations can fail for several reasons, including:

Invalid API credentials
Provider connectivity problems
Unsupported models
Invalid dimensions
Rate limits
Service errors
Incompatible vector storage

Applications should handle provider errors appropriately and avoid treating failed embedding operations as successful indexing.

Security and Privacy

Embeddings can represent information derived from sensitive documents. Applications should consider:

What data is sent to hosted embedding providers
Whether sensitive content can leave the deployment environment
Storage security
Tenant isolation
Access controls
Data retention
Credential management

For sensitive workloads, embedding-provider selection should take privacy and deployment requirements into account.

Best Practices

Use the same compatible embedding model for indexing and querying.
Keep vector dimensions consistent with vector storage.
Choose chunk sizes appropriate to the source documents.
Preserve useful metadata with embedded content.
Re-embed documents when the embedding model changes.
Rebuild indexes when dimensions or incompatible embedding models change.
Use local/deterministic embeddings for development and testing where appropriate.
Use hosted embedding providers according to their API and privacy requirements.
Keep embedding generation separate from agent business logic.
Combine vector retrieval with BM25 when hybrid search is beneficial.
Use reranking when additional relevance refinement is needed.
Test retrieval with representative documents and questions.
Do not hard-code API credentials.
Treat embedding data as potentially sensitive application data.

Current Project Status

BindAI currently provides a concrete embedding layer. Implemented components include:

EmbeddingProvider
RandomEmbeddingProvider
OpenAIEmbeddingProvider
Configurable OpenAI embedding model
Configurable OpenAI embedding dimensions
Embedding integration with vector-oriented retrieval
Embedding support within the broader Knowledge architecture

The embedding layer works alongside:

Document processing
Chunking
Vector retrieval
BM25 retrieval
Hybrid retrieval
Metadata filtering
Reranking
Conversational retrieval
Knowledge pipelines
Agent Knowledge integration

Summary

Embeddings convert text into numerical vectors that can be used for semantic retrieval. BindAI provides an embedding abstraction with both local/deterministic and OpenAI implementations:

Text
 |
 v
EmbeddingProvider
 |
 +---- RandomEmbeddingProvider
 |
 +---- OpenAIEmbeddingProvider
 |
 v
Vector

Embeddings can then participate in Knowledge and retrieval pipelines:

Documents
   |
   v
Chunking
   |
   v
Embeddings
   |
   v
Vector Retrieval
   |
   v
Filtering / Reranking
   |
   v
Relevant Context
   |
   v
Agent
   |
   v
Language Model

Embeddings are therefore a concrete part of the current BindAI Knowledge and retrieval architecture rather than only a planned feature. Applications should nevertheless keep embedding generation, vector storage, retrieval, and agent execution as separate concerns so that each component can evolve independently.

​Embeddings

​What Is an Embedding?

​EmbeddingProvider

​RandomEmbeddingProvider

​OpenAIEmbeddingProvider

​Embedding Dimensions

​Why Embeddings Are Useful

​Semantic Search

​Document Embeddings

​Query Embeddings

​Vector Search

​Embeddings and Retrieval

​Hybrid Retrieval

​Embeddings and Reranking

​Embeddings and Knowledge

​Embeddings and Memory

​VectorMemoryProvider

​Embeddings and Vector Storage

​OpenAI Embeddings Configuration

​Embedding Provider Selection

​Embedding Model Consistency

​Changing Embedding Models

​Embedding Quality

​Embeddings and Document Chunking

​Embeddings and Metadata

​Embeddings in a RAG Pipeline

​Embeddings Are Not Tools

​Embeddings and Agents

​Embedding Errors

​Security and Privacy

​Best Practices

​Current Project Status

​Summary